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Datatrieve Version V1.1 Release Notes 
General Notes 



1 . General notes 

Datatrieve Version 1.1 is strictly upwards compatible from 

Version 1.0. The dictionary format has not changed; all 

domains, records, procedures, and command files used for 

Version 1.0 may be used without modification on Version 1.1. 



NOTE 

Although the maintenance 
release of Datatrieve-1 1 is 
designated as Version 1.1, the 
corresponding version of the 
software is VOL 10. The 
latter designation appears in 
the start-up banner of 



UCU ly I 



2.0 Installation Procedure Changes 

Datatrieve Version 1.1 is built with a fixe* 
dictionary and^ messages file. This has two direct effects 
on the installation procedure: 

1. The installation procedure is now completely 
automated . 

2. Installation must be performed from a; privileged 
account . 

Both the dictionary and the message file are installed in 
LB: [1,2] for all operating systems but RSTS where they 
reside on SY: [1,2]. 

See the Datatrieve-1 1 Installation Guide for the specific 
installation procedures. 
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3.0 Changes and Additions 

The following changes and additions have been made to the 
Datatrieve Version 1.1 software and are not documented in 
the Datatrieve-1 1 User's Guide. 



3.1 Tutorial Software Added (Guide Mode) 

A CRT based tutorial has been added to Datatrieve Version 
1.1. The tutorial feature can be used only by VT100, VT52, 
and VT52 compatible terminals. A tutorial session is 
entered by the Datatrieve command: 

SET GUIDE 

The software is self documenting. 

Typing SET GUIDE from an unsupported terminal produces the 
prompt: 

ENTER TERMINAL TYPE: 

Although you must enter a character, all responses result in 
the message: 

Terminal not supported for guide mode. 



3.2 CONTAINING Relational Operator Added 

The substring search relational operator CONTAINING has been 
added. CONTAINING is used in a record selection expression 
to retrieve records with a field containing a particular 
substring. The substring may be anywhere in the field, and 
need not match the case (upper/lower case) of the search 
string. For example, the command: 

FIND BOOKS WITH TITLE CONTAINING "LASER" 

finds all records in BOOKS with the word "laser" somewhere 
in the field TITLE. 



3.3 Command Interruption Supported 

A command may be interrupted on the RSTS/E ; RSX-11M ? and 

VAX/VMS operating systems by typing ~C. After recognition 

of the "C, Datatrieve returns to the DTR> command level. 
This feature is not available on IAS. 



{ 
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Care should be exercised to avoid typing a second ~C before 
Datatrieve has returned to its command level. 



3.4 SET/SHOW DICTIONARY Commands added 

The data dictionary may be changed during a Datatrieve 
Version 1.1 session with the command: 

SET DICTIONARY file-spec 

where "file-spec" is the file specification of a data 
dictionary. If the file does not exist, cannot be accessed, 
or is not a valid dictionary, the former dictionary 
assignment remains in effect. To return to the default 
system dictionary, type the command: 

SET DICTIONARY 

To display the current dictionary, type: 

SHOW DICTIONARY 

Since Datatrieve 1.1 is built with a central dictionary, SET 
DICTIONARY is the prefered way to access a private 
dictionary. A private dictionary may be created by copying 
the system dictionary with PIP, COPY, or the QCPRS utility 
program, or by the following RMS define utility command: 

DFN PRIVAT.DIC /FO:IDX /RF:FIX:512 /AL:100 /BK:2- 
/KY:30:2: (/OP:DUP) /KY:0:31: (/OP:NODUP) 



3.5 Data Input Prompt Shortened 

The prompt message has been changed from: 

Please supply value for PROMPT-NAME: 
to: 

Enter PROMPT-NAME: 

3.b Unquoted Literal Strings Accepted 

An undefined name on the right hand side of a relational 
expression is assumed to be a literal string. The 
Datatrieve statement: 
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PRINT YACHTS WITH BUILDER EQ PEARSON 

would be rejected as an error (Unknown field name "PEARSON") 
in version 1.0 of Datatrieve. In Version 1.1, Datatrieve 
issues the warning message: 

"PEARSON" is not field, assumed literal 

and executes the command as if it had been entered: 

PRINT YACHTS WITH BUILDER EQ "PEARSON" 

Datatrieve does not interpret an unquoted string as a 
literal if the string is known as a keyword, a domain name, 
a collection name, or a record name. Nor does Datatrieve 
treat an unquoted string as a literal if it is on the left 
side of a relational expression. Datatrieve automatically 
converts unquoted literal to upper case. 



3.7 Command Input Prompts Now Indicate Context 

The input prompt changes depending on the context within 
Datatrieve. The following prompts are used: 



Prompt Meaning 

DTR> Datatrieve is waiting for a command 

DFN> A dictionary element is being defined 

RW> The report writer is waiting for a command 

QED> The editor is waiting for a command 

IN> The Datatrieve editor is in input mode 

3.8 Characters tolerated in Numeric Input Fields 

The charcters percent (%) , comma (,), and dollars ($) are 
tolerated if entered in response to an input prompt for a 
numeric field. The characters are ignored. In Version 1.0 
of Datatrieve, the presence of any of these characters would 
have forced a warning message. 
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3.9 Special Input Sequence Leaves Field Unchanged 

The input sequence <tab><carriage-return> , when given in 
response to a prompt for a STORE, MODIFY, or assignment 
statement causes the field to remain unchanged. 



3.10 Relational Expression Syntax Broadened 
Relational expressions of the form: 

field-name NOT relation value 

are now accepted by Datatrieve where "field-name" is a field 
name, "relation" is a relational operator (EQ, NE, BETWEEN, 
etc.), and "value" is a value expression. The effect is 
identical to the construct: 

NOT field-name relation value 

In other words, the following statement is now legal: 

FIND YACHTS WITH LOA NOT BETWEEN 30 AND 40 

3.11 Miscellaneous Syntax Additions 

The keyword "BUT" has been added as a synonym of "AND". 
This allows commands such as: 

PRINT YACHTS WITH PRICE<20000 BUT L0A>30 

The keyword "AND" may be used in place of or in conjunction 
with a comma when separating print objects in a print list. 
Hence the following commands are valid: 

PRINT TYPE, RIG, AND PRICE OF YACHTS 

PRINT RIG AND PRICE 



3.12 Restrictions on Procedures Removed 

Most restrictions on the types of commands which may be 
placed in procedures have been lifted. In the maintenence 
release, any command except DEFINE may be included in a 
procedure. This specifically includes READY and SHOW. 
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3.13 REDEFINES Clause Supported 

The COBOL record definition clause REDEFINES is supported. 
The following is an example of the REDEFINES clause: 

03 DATES. 

05 DATE PIC X(6) EDIT-STRING IS XX/XX/XX . 
05 SEP-DATE REDEFINES DATE. 

07 MONTH PIC 99. 

07 DAY PIC 99. 

07 YEAR PIC 99. 

The field SEP-DATE redefines the field DATE in that it 
provides an alternate description of the same data. 
Specifically, the field MONTH is the first two bytes of the 
field DATE, the field DAY is the third and fourth bytes of 
DATE, and the field YEAR is the last two bytes of DATE. 
This allows you to enter separate values for the month, day, 
and year field, to sort the file based on the natural order 
of dates, yet print the date with a standard default format. 
The redefining field must be contained in the same group as 
the original field, must have the same level number, and 
must be exactly the same length as the original field. 
Redefinitions are ignored in PRINT and MODIFY lists unless 
referenced explicitly. 



3.14 Nested Procedures Supported 

Procedures may contain references to other procedures 

(nested procedures) provided that no procedure invokes 

itself either directly or indirectly. The maximum depth of 
procedure nesting varies from about 10 to about 30 depending 

on the amount of memory available, number and size of 
established collections, etc. 



3.15 Procedure Editor Added 

A Datatrieve procedure editor has been added. The editor is 
invoked by the command: 

EDIT procedure-name 

where "procedure-name" is the name of an existing procedure. 
The editor is a small subset of EDT, the DEC Standard 
Editor. See Appendix A for the editor specification. 
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3.1b DEFINE FILE Command Added 

A command to create the RMS file for a domain has been 
added. The syntax of the command is: 

DEFINE FILE FOR domain [option-1] [, option-2...] 

where "domain" is a domain name. Each "option" must be one 
of the following: 

ALLOCATION=blocks 

SUPERCEDE 

KEY=field [(key-modifiers...)] 

where "blocks" is the number of disk blocks to be allocated 

for the file, "field" is the name of a field in the domain 

to be used as a key, and "key-modifiers" are one or two 
modifiers from the list: 

CHANGE 

NO CHANGE 

DUP 

NO DUP 

If two key modifiers are given, they must be separated by 
commas . 

Any number of keys may be specified (up to a maximum of 
254); if no keys are specified a sequential file is 
created . 

To define a file, the following conditions must be met: 

1. The domain must be defined in the dictionary. 

2. The record referenced in the domain definition must 
be defined in the dictionary. 

3. The user must have control access to the domain. 

An indexed file is created if at least one KEY is specified; 
if no keys are specified, the file created is sequential. 
If more than one key is specified, the first is the primary 
key, the second the first alternate key, etc. The default 
options for the primary key are (NO CHANGE, NO DUP). For 
alternate keys the defaults options are (CHANGE, DUP). 

For all files, the record format is fixed length with the 



Datatrieve Version VI. 1 Release Notes PAGE 8 

Changes and Additions 



length determined by the record definition. The device, UIC 
or PPN, file name, extention, and version number are taken 
from the domain definition. 

Examples : 

DEFINE FILE FOR YACHTS KEY=BUILDER (NO CHANGE, DUP), 

Tvr?\r m nrvnt 
J\C I=l v lUl>'tL , 

ALL0CATI0N=30, SUPERCEDE 

DEFINE FILE FOR YACHTS 

In the first example, an indexed file with two keys is 
created. The first key corresponds to the field BUILDER in 
the record definition (YACHT) associated with the domain 
YACHTS, and has the NO CHANGE, DUP attributes. Duplicate 
values are allowed for the BUILDER field, but once stored, 
that field may not be modified. If NO DUP were specified, 
any attempt to store a second record with the same builder 
would be rejected. The second key corresponds to the field 
MODEL, may be modified, and may have duplicates. 

On RSTS/E, the option SUPERCEDE indicates that the old 
version of the file specified in the domain definition 
(YACHT.DAT) should be deleted and replaced with the new 
version. Without the SUPERCEDE option DEFINE FILE will not 
create a new file on RSTS if a file of the same name exists 
in the designated directory. 

On RSX-11M, IAS, and VAX/VMS, DEFINE FILE creates a new 
version of the file unless the version number is explicit in 
the domain definition. In that case, SUPERCEDE can be used 
to create another file with the same extention, and delete 
the old one. 

In the second example, a sequential file is created. It too 
uses the record description YACHT to determine the record 
length, and the domain definition of YACHTS to find the file 
name. is lost. If an error is found, correct it 
immediately, or cancel the edit with the editor QUIT 
command. 



3.17 DELETE Command Improved 

An unsuccessful DELETE command no longer kills command 

files. A command file containing a record definition may 

conveniently contain a command to delete the previous 
definition . 
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3.18 MODIFY VERIFY Supported 

The VERIFY USING clause is now supported on the MODIFY 
command. It works the same way as does the VERIFY clause on 
the STORE command. 



3.19 MODIFY USING Supported 

The USING clause on the MODIFY command is recognized in 
Datatrieve version 1.1. The syntax of the USING form of 
MODIFY is: 

MODIFY [ALL] USING stmt-1 [VERIFY USING stmt-2] [of rse] 

where stmt-1 is a single Datatrieve statement (simple or 
compound) containing at least one assignment statement. 



3.20 Definition of Privileged User Changed 

A login project code of one is now required to get 
automatic, de facto control access to dictionary elements. 
In Version 1 . of Datatrieve, any login project code less 
than eight was sufficient. 



3.21 DEFINE RECORD Command Gives Record Length 

The DEFINE RECORD command, when successful, issues a message 
containing the length in bytes of the record defined. 



3.22 Percent Character Allowed in EDIT-STRING 

The special symbol % is allowed in EDIT-STRING. It is 
treated as a literal character. For example, the command: 

PRINT 15 USING 99% 

prints as: 

15% 
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3.23 Command Line Command Files Supported 

If Datatrieve is installed (on RSX-1 1M or IAS) or invoked 
via a CCL (on RSTS), any data on the invocation line is 
accepted by Datatrieve as the sole input, i.e. Datatrieve 
executes the line (or command file) and exits immediately. 

For example, if Datatrieve were installed (INS command on 
RSX-1 1M and IAS, a CCL on RSTS/E), the acceptance test could 
be run by the operating system command: 

DTR §DTR.TST 



3.24 Statistical Operators Print Default Changed 

When used in a print list, MAX, MIN, and AVERAGE of a single 
field acquire the same default column header and edit string 
as the field itself. 



3.25 Underscore Character Accepted in Names 

The underscore character (_) is permitted in Datatrieve 
names provided that it is neither the first nor last 
character . 



3.2b Report Writer Formatter 

An initial literal (or skip followed by a literal) in a 
print list is now aligned with the first column of data, to 
the first logical columns .group. See the procedure 
LOA-REPORT in the Version 1.1 acceptance test for an 
example . 



3.27 Packed Decimal Datatype Supported 

The packed decimal datatype is supported. A number is 
represented in packed decimal as a sequence of 4 bit 
nibbles, stored two nibbles per byte. The low order byte 
(high address) of a packed decimal field contains only one 
digit nibble, plus a sign nibble. The sign nibble must 
contain either one of the positive sign codes (10, 12, 14, 
15, decimal) or one of negative sign codes (11 or 13 
decimal). A packed decimal field is indicated in the record 
definition by a USAGE of COMP-3. For example, the field 
definition 
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05 NUMBER-ON-HAND PIC S9(5) USAGE COMP-3 

defines a packed decimal field 3 bytes long. 

The packed decimal datatype used by Datatrieve is compatible 
with the packed decimal used by VAX-1 1 hardware, the RPG-II 
language, and IBM hardware. 



3.28 Context rules expanded for STORE USING statement 

The recognition rules for names occurring on the right hand 
side of assignment statements have been modified. Now, 
references to data in fields in the record can be stored. 
Two conditions must be met: 

1. A context variable must be present on the STORE 
USING statement. The syntax is 

STORE context IN domain USING statement 

where "domain" is the domain into which the new 
record is to be stored, "context" is the context 
variable, and "statement" is a Datatrieve 
statement. 

2. Any reference to a field in the record being stored 
must be explicitly qualified by the context 
variable. 



Examples : 



STORE NEW IN REVENUES USING 
BEGIN 



Q1=*.Q1 
Q2=*.Q2 

Q3=*.Q3 
Q4=*.Q4 



FIRST QUARTER 
SECOND QUARTED 
THIRD QUARTER 
LAST QUARTER 



YEAR-TOTAL r NEW.Q1 + NEW.Q2 + NEW.Q3 +NEW.Q4 



END 
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STORE SAIL IN YACHTS USING 
BEGIN 

LOA=*.LOA 

IF SAIL.LOA NOT BETWEEN 20 AND 45 THEN 

PRINT "BAD LENGTH-OVER-ALL, RE-ENTER" THEN 

L0A=*.L0A-AGAIN 

END 



3.29 Prompts Supported for Report Writer Parameters 

If a REPORT-NAME is not included in a report specification, 
Datatrieve Version 1.1 prompts for one. The report name 
entered must conform to the same rules as SET REPORT-NAME. 
It can not be longer than the input line, although it can 
include slash characters so that it will print on more than 
one line. 

The report writer also supports *. prompts for both SET 
LINES-PAGE and SET COLUMNS-PAGE. 



3.30 Scope of prompts in loops fixed 
In version 1.0 the command: 

REPEAT 5 PRINT YACHTS WITH BUILDER EQ *. BUILDER 

prompts once for BUILDER, then prints the same list of 
YACHTS five times. In Version 1.1 of Datatrieve , that 
statement prompts five times, print a list each time. 

3.31 Record Definition Length Limitation Removed 

The Version 1.0 limitation on the maximum length of 

dictionary elements (record definitions) has been 

eliminated. There is no practical bound on the length of a 
record or procedure definition. 

3.32 Dictionary Compression Utility Added 

A data dictionary file compression utility (QCPRS) has been 
provided. See the Datatrieve Installation Guide for 
SDecif ications . 
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3.33 Emulation of Floating Point Processor Added 

A floating point processor is no longer necessary to process 
the floating point datatypes COMP-1 and COMP-2. If a 
floating point processor is present, Datatrieve 
automatically uses it. If a floating point processor is not 
present, Datatrieve emulates the floating instructions. 



3.34 Built with RMS Runtime System on RSTS 

Datatrieve Version 1 . 1 on RSTS/E is built with the RMS 
runtime system to improve performance and increase the 
maximum task extension quantity. 



3.35 Maximum Keys per Index Files Controllable 

Datatrieve Version 1.0 could READY indexed files with a 
maximum of 10 keys. In Datatrieve Version 1.1, the maximum 
number of keys can be controlled with the global symbol 
MAXKEY in the task build command file (DTR11M.TKB, 
DTRIAS.LNK, DTRVAX.TKB, or DTRSTS.TKB). To increase the 
maximum number of keys accessable by Datatrieve, edit the 
appropriate task build file to increase the value assigned 
to MAXKEY, and rebuild Datatrieve. 
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4.0 Restrictions and Limitations 



4.1 Collection Sizes 

The maximum size of an established collection (resulting 
from execution of a FIND statement) is about 5,000 records. 
To circumvent this limitation, use RSE forms of the various 
Datatrieve statements. This also improves performance. 



4.2 Dictionary Access on VAX/VMS 

VAX/VMS does not support record locking in compatibility 
mode. To avoid problems associated with a shared data 
dictionary, Datatrieve opens the dictionary only when 
required. Occasionally, however, the dictionary may not be 
available when required. When this happens, Datatrieve 
waits five seconds, and attempts to re-access the 
dictionary; if necessary, it repeats this three times. If, 
at the end of 15 seconds, the dictionary is still not 
accessable, the operation is cleanly aborted leaving the 
dictionary unchanged. 



4.3 Computing Ratios of Statistical Expressions 

When it is necessary to compute the ratio of two statistical 
expressions, enclose each in parentheses to avoid ambiguity. 
For example, avoid expressions like 

TOTAL PRICE / TOTAL COST 

using instead the expression 

(TOTAL PRICE) / (TOTAL COST) 



4.4 Arithmetic Limitations 

In general Datatrieve is capable of arithmetic operations of 
up to 18 decimal digits. The multiplication and division 
operations (including TOTAL), however, are limited to 
operands and results with an absolute value less than 2**31 
(about nine decimal digits). 

Floating point calculations (expressions containing a field 
defined with a USAGE of COMP-1 or COMP-2) are limited by the 
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accuracy of the data type used. 



4.5 GUIDE, High Baud Rates, and RSX-1 1M 

When GUIDE mode is set, Datatrieve interrogates the user's 
terminal to determine its type. On RSX-1 1M, particularly 
with a VT100 transmitting above 1200 baud, the terminal may 
respond faster than Datatrieve can react. If this happens, 
one of the messages: 

Terminal not support for GUIDE mode 

Enter terminal type: 

will result. 

To overcome this problem, one of two solutions may be used: 

1. If split baud rates are available, set the terminal 
to transmit at 150 or 300 baud. 

2. Hard code the terminal type in the Datatrieve task 
build command file (DTR11M.TKB) and rebuild 
Datatrieve. The terminal type is controlled by the 
global TRMTYP. A value of indicates that the 
terminal is to be determined; a value of 1 
indicates a VT52; a VT100 is indicated by a value 
of 2. 



APPENDIX A 
Datatrieve Procedure Editor 



The command EDIT procedure-name invokes an editor which can 
insert, replace, or delete text from procedures defined in 
the Data Dictionary. 

The new version of the procedure replaces the old; if you 
realize during an edit that you have made a serious error, 
leave the editor with the command QUIT which kills the edit 
and restores the old version of the procedure. 



A.1 Editor Summary 

Purpose 

This command invokes a subset of the DEC 
Standard Editor (EDT), opens the selected 
procedure to the editor, and changes the 
prompt from DTR> to QED>. When you have 
finished editing the procedure issuing an 
EXIT command or ~Z replaces the old version 
with the new, and return you to Datatrieve. 

Format 

EDIT procedure-name [(password)] 



Datatrieve Procedure Editor 
Overview 
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A. 1.1 Summary of EDIT commands 

All of the editor commands follow the general syntax: 

command [range-specification] 

where "command" is one of the editor commands, 
"range-specification" is a range specification. 

The commands are: 



and 



T(YPE) 



<cr> 



D(ELETE) 
S(UBSTITUTE) 

R(EPLACE) 



WMO£,n i j 



EX(IT) 



QUI' 



TYPE displays lines. Used alone it displays 



the next line. When followed 
displays the current line. 



by a 



it ii 



it 



<cr> is an acceptable abbreviation for TYPE. 
Thus entering a carriage return without a 
command before it displays (and advances the 
cursor to) the next line. 



DELETE deletes the line described 
range specification. 



by the 



SUBSTITUTE searches for a string of 
characters and substitutes a second string of 
characters for them. 

REPLACE deletes the line described by the 
range specification and enters INSERT mode to 
accept a replacement which can be longer or 
shorter than the original. 

INSERT changes the editor from command mode 
to insert mode, changing the prompt from QED> 
to IN>. All input is inserted into the 
procedure until a ~Z is entered, when the 
editor returns to command mode. 

EXIT is the normal way of leaving the editor. 
It replaces the old version of the procedure 
with one just created. 

QUIT is an abnormal ending to an edit. The 
new version of the procedure is deleted, and 
the old version is restored. Use it when 



gune a wry 



AnTT _ _ ._ -- _ i. 1- _ 

yuxi <jcfn nou ue 



abihvov-i pl-orl 



Datatrieve Procedure Editor PAGE A-3 

Overview 



A. 1.2 Summary of EDIT ranges 

Single range specifications place the editor at the 
beginning of the line specified. They are: 



" . " A period specifies the current line. It is 

the default range for all the commands except 
TYPE. 

%BE(GIN) The first line of the procedure. 

%E(ND) The end of the procedure. 

'string' or "string" 

The next line containing the string. 

%WH(OLE) The whole procedure. 

%R(EST) The rest of the procedure (including the 
current line) . 

%BEF(ORE) All the lines between the first and the 
current, inclusive. 

%ALL 'string' or %kLL "string" 

Every line containing the string. 



Range specifications can be connected. The 
position of the editor after using combined 
range specifications is not easily 
predictable. The connectors are: 



%FOR or ; 



Lines from range-1 through range-1 plus n. 



%AND or , The line described by range-1, and the line 

described by range-2, etc. 

+ The line n lines after the line described by 

range-1 . 
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A. 2 Editor Commands 



A. 2.1 Delete one or more lines -- DELETE 
Purpose 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



Hints 



The DELETE command is used to delete one or 
more lines from a procedure. 



DELETE [range-1] 
D [range-1 ] 

1. If you specify range-1, it must be a 
valid range specification 



None . 



None . 



1. If you supply a range specification, the 
line or lines identified by range-1 are 
deleted from the procedure. 

2. If you do not supply a range 
specification, the current line is 
deleted from the procedure. 

3. The editor is now positioned at the line 
following the last line deleted. 



DELETE 

DELETE %kLL "BOTTOM OF" 

Remember that DELETE deletes complete lines 
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The second example above deletes all the 
lines containing the string "BOTTOM OF", not 
just the characters "BOTTOM OF". 
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A. 2. 2 Exit from the Editor -- EXIT 

Purpose 

The EXIT command terminates the editor, 
stores the updated procedure in the data 
dictionary, and returns control to 
Datatrieve. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Example 



Hints 



EXIT 
EX 



The updated procedure must not be empty. 



Datatrieve returns with the DTR> prompt. 



1. The editor is terminated. 

2. The edited procedure is written back to 
the data dictionary in place of its 
original definition. 

3. Control is returned to Datatrieve. 

4. The old definition of the procedure is 
deleted . 



EXIT 



Before exiting the editor, it is good 
practice to print the entire procedure to 
verify that the intended modifications were 
made correctly. Once the editor is exited, 
the old procedure definition is lost. If an 
error is found, correct it immediately, or 
cancel the edit with the editor QUIT command. 
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A. 2. 3 Insert one or more lines -- INSERT 



Purpose 



Tne insert command allow new lines to be 
inserted into a procedure. 



Format 



INSERT [range-1] 
I [range-1 ] 

1. If you specify range-1, it must be a 
valid range specification 



Rpnni rpmpnf.s 



Prompts & 
Responses 



None 



The prompt changes from QED> to IN> when in 
insert mode. 



Effects 



Examples 



1. The editor enter insert mode. Subsequent 
lines typed are inserted in the 
procedure. Insert mode is terminated by 
typing a <control-Z>. 

2. If you do not supply a range 
specification, the new lines are inserted 
ahead of the current line. 

3. If you supply a range specification, the 
new lines are inserted ahead of the first 
line indicated by the range 
specification . 



INSERT %BEGIN 



Hints 



To insert lines after the bottom line, the 
following procedure may be used: 
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1. Position the editor at the end of 
the procedure by typing the command 
%END (an implicit TYPE command). 

2. Type the INSERT command to enter 
insert mode. 
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A. 2. 4 Abandon the Editor -- QUIT 

Purpose 

The QUIT command is used to abort an edit and 
return to Datatrieve without alter the 
procedure being edited. 



Format 



Requirements 



Prompts & 

Rp <;nnn «i<=><5 



Effects 



Examples 



Hints 



QUIT 



None. 



None . 



1. The editor is terminated. 

2. No modifications to the procedure are 
made. 

3. Control is returned to Datatrieve. 



QUIT 



QUIT undoes any damage you may have 
inadvertently done to your procedure. QUIT 
when you're behind. 
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A. 2. 5 Replace One or More Lines — REPLACE 

Purpose 

This command may be used to replace one or 
more complete lines with completely new 
lines. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



REPLACE [range-1] 
R [range-1 ] 

1. If you specify range-1, it must be a 
valid range specification 



None . 



The prompt changes from QED> to IN> when in 
insert mode. 



1. If you specified a range, the line or 
lines identified are deleted from the 
procedure . 

2. If you do not specify a range, the 
current line is deleted from the 
procedure . 

3. The editor enters insert mode. 
Subsequent lines typed are inserted in 
the procedure. Insert mode is terminated 
by typing a <control-Z>. 

4. The editor is now positioned at the line 
following the last line deleted (after 
the last line inserted) . 



R %WHOLE 
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Hints 

Do not confuse REPLACE with SUBSTITUTE. The 
former replaces lines, the latter substitutes 
strings . 



Datatrieve Procedure Editor PAGE A-12 

Editor Commands 



A. 2. 6 Substitute One Character String for Another -- Substitute 

Purpose 

This command substitutes one character string 
for another. It may substitute only the 
first occurrence, or all occurrences of a 
string . 



Format 



Requirements 



Prompts & 
Responses 



Effects 



ExamDles 



SUBSTITUTE /string-1 /string-2/ [range-1] 
S /string-1 /string-2/ [range-1] 

1. If you specify range-1, it must be a 
valid range specification 

2. The delimiting character "/" may be 
replaced with any printing character. 



None . 



All lines in which substitutions take place 
are typed. 



1. If you supply a range specification, all 
occurrence of string-1 in all lines 
identified by range-1 are replaced with 
string-2. Any lines identified by 
range-1 which do not contain string-1 are 
not modified . 

2. If you do not supply a range 
specification, only the first occurrence 
of string-1 is replaced with string-2. 
If string-1 is not found between the 
current line and t ft e end of the 
procedure, no substitution is performed. 



SUBSTITUTE /PRINT/PRINP/ 
S ®PRICE/LOB*PRICE/LOA* 
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S /FOOPAR/FOOBAR/ %WHOLE 

Hints 

Substitution of one string for another is 
probably the easiest strategy to follow when 
making minor modifications to a procedure. 
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A. 2. 7 Display One or More Lines — TYPE 

Purpose 

The TYPE command is used to print one or more 
lines in a procedure. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



TYPE [range-1] 
T [range-1 ] 
[range-1 ] 

1. If you specify range-1, it must be a 
valid range specification 



None . 



The appropriate lines are displayed on your 
terminal . 



1. If you supply a range specification, the 
lines identified by range-1 are displayed 
on your terminal. Following completion 
of the command the editor is now 
positioned at the first line displayed. 

2. If you do not supply a range 
specification, the editor automatically 
advances to the line following the 
current line, and displays that line. A 
TYPE command without a range 
specification is equivalent to the 
command 

TYPE .+1 



1 If L 

T %WHOLE 
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T . 



Hints 

Note that the TYPE command does not require 
either "T" or "TYPE" to be included in the 
command. A range specification alone is 
interpreted as a TYPE command. A blank line, 
in turn, is considered an implicit TYPE 
command without a range specification. For 
this reason, simple carriage-returns may be 
used to scroll thru a procedure. For short 
procedures, this is an excellent mechanism 
for locating a particular line. 



Datatrieve Procedure Editor PAGE A-16 

Range Specifications 

A. 3 Range Specifications 



A. 3.1 The Current Line -* . (period) 

Purpose 

This range specification indicates that the 
editor command is to act on the current line. 

Format 

1. A period. 



Requirements 



Prompts & 
Responses 



Effects 



None . 



None. 



i-i a cuup_i_ c o 



Hi n f. <5 



1. The command acts on the current line. 

2. If you entered a period without a 
command, the current line is typed. 



TYPE . 

S/ORIGINAL STRING/REPLACEMENT STRING/ . 



A Type command with a range of <period> types 
the current line without advancing to the 
next line. 

A Substitute command with a range of <period> 
replaces all occurrences of the original 
string on the current line with the 
replacement string. Without any range, the 
same substitute command would replace only 
the first occurrence of the original string 
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on the line. 
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A. 3. 2 The First Line of a Procedure -- fcBEGIN 

Purpose 

This range specification indicates that the 
editor command is to act on the first line of 
the procedure. 



Format 


%BEGIN 
%BE 


Requirements 


None. 


Prompts & 
Responses 


None . 


Effects 





Examples 



Hints 



1. The command containing the ^BEGIN acts on 
the first line of the procedure. 

2. If you entered %BEGIN without an explicit 
command, the first line of the procedure 
is typed. 



TYPE %BEGIN 
DELETE %BEGIN 



%BEGIN typed without a command (equivalent to 
TYPE %BEGIN) is a convenient way to get to 
the first line of the procedure. 
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A. 3. 3 The last line of the procedure -- $END 

Purpose 

The %END range specifies that the editor is 
to apply the command to the last line of the 
procedure . 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Example 



Hints 



%END 



None. 



None. 



1. The command acts on the last line of the 
procedure . 

2. If you entered a period without a 
command, the last line is typed. 



INSERT %EHD 

The command 

INSERT %END 

is the best way to add new lines after the 
last line of a procedure. 
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A. 3.4 The Next Occurrence of a String 

Purpose 

This range specification indicates that the 
editor command is to be applied to the next 
line containing a given string. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



"string-1 " 
1 string-1 ' 

1. The string may be enclosed in either 
single or double quotes. 



When the string is not found between the 
current line and the end of the procedure, 
the command has no effect. 



A messages is printed if the string is not 
found . 



1. The command containing the range 
specification acts on the next line 
containing the string-1. 

2. If the string-1 is not found, the command 
is aborted. If this happens, the result 
is just as if the command were not typed. 

3. The search for string-1 is case 
insensitive. An upper case letter 
matches is lower case equivalent and vice 
versa . 



TYPE "AT BOTTOM" 
DELETE 'PRINX YACHTS'" 



Hint 
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A quoted string without an explicit command 
is a dandy way to locate and print a 
particular line. 
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A. 3. 5 The whole procedure -- %WHOLE 

Purpose 

The range %WHOLE specifies that the command 
is apply to all lines of the procedure. 



Format 






%WHOLE 




%WH 


Requirements 






None. 


Prompts & 




Responses 






None. 


Effects 





Examples 



Hints 



1. The command acts on all lines in the 
procedure. 

2. If you entered %WHOLE without a command, 
the .entire procedure is typed. 



%WHOLE 
S/PLATAPUS/PLATYPUS/ %WHOLE 



If you become seriously lost during an edit, 
type 

%WHOLE 

to determine the extent of the damage and 
position the editor on the first line of the 
procedure. And, if worse comes to worse, the 
command 

REPLACE %WHOLE 

is a good way to start over (though you might 
consider QUIT). 
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A substitution command with the range %WHOLE 
changes all occurrences of the original 
string in the procedure to the replacement 
string. 
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A. 3. 6 The Rest of the Procedure -- %REST 

Purpose 

This range specification indicates that the 
editor command is to act on all lines from 
the current to the last line of the 
procedure . 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



XREST 



None. 



None . 



1. The command acts on the current and 
remaining lines of the procedure. 

2. If 5&REST is entered without an explicit 
command, the rest of the lines are typed. 



D $REST 
ftREST 
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A. 3. 7 The preceding lines -- ^BEFORE 

Purpose 

The ^BEFORE range specification applies the 
editor command to all lines from the first to 
the current line. 



Format 



%BEFORE 
%BEF 



Requirements 

None. 



Prompts & 
Responses 



Effects 



None. 



Examples 



Hints 



1. The command acts on all lines from the 
top of the procedure to and including the 
current line. 

2. If 5&BEF0RE is entered without an explicit 
command, the first through the current 
lines are typed. The editor, however, is 
positioned to the first line of the 
procedure after the command. 



S/PRINT ALL/PRINT/ ^BEFORE 



Since almost any use of %BEFORE causes the 
editor to be positioned to the first line of 
the procedure, ^BEFORE is of limited use. 
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A. 3. 8 All Lines Containing a Particular String -- %ALL 

Purpose 

The range %kLL is used to apply an editor 
command to all lines containing a particular 
string . 



Format 



Requirements 



Prompts & 
Responses 



Effects 



ExamDles 



Hints 



%kLL "string-1" 
%ALL 'string-1 f 

1 . The string may be enclosed in either 
single or double quotes. 



None . 



No indication is given if no occurrence of 
string-1 was found. 



1. The command contain the %ALL range acts 
on all lines containing the string-1. 

2. If the range is given without an explicit 
command, all lines containing the given 
string are typed. 

3. The search is case insensitive. 



TYPE %KLL "EDIT-STRING" 
DELETE %ALL 'PRINT "' 



The range %ALL can be used to print all 
occurrences of a particular field in a 



« 
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A. 3. 9 Repeat for a Number of Consecutive Lines -- %FOR 

Pu r po s e 

This range specification allows a command to 
be applied to a number of consecutive lines. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



range-1 %FOR n 
range-1 ; n 

1. Range-1 must be one of the range 
specifications: , (period), %BEGIN, 
quoted or double quoted string. 

2. N must be an unsigned, non-zero number. 



None . 



None . 



1. The command is applied to n lines 
beginning with the line identified by 
range-1 . 

2. If the range is entered without an 
explicit command, the n lines are typed. 



T %BEGIN ; 5 
DELETE . %FOR 3 
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A. 3. 10 Multiple Range Specification -- %AND 

Purpose 

This range form allows two or more simple 
range specifications to be given for a single 
command . 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



range-1 %AND range-2 . . . 
range-1 , range-2 . . . 

1. Range-1, range-2, etc. must be taken 
from the following list of range 
specifications: . (period), %BEGIN, 
%EN'D, quoted or double quoted string. 



None . 



None . 



1. The command is applied to the line 
identified by range-1, then to the line 
identified by range-2, etc. 

2. Following execution of the command, the 
editor is positioned at the line 
identified by range-1, unless that line 
was deleted. In that case the editor is 
positioned where the line used to be. 

3. If the range is entered without an 
explicit command, the lines indicated by 
the various ranges are typed. The editor 
is now positioned at the line identified 



by r ai 



,_ 1 



TYPE %BEGIN, %END 
TYPE %BEGIN. "F00" 
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Hints 

The command: 

%BEGIN. "FOQ" 

can be used to type the line containing the 

first occurrence of the string "F00". The 

editor, however, is now positioned at the 
first line of the procedure. 
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A. 3. 11 A Fixed Offset from a Given Line — + 

Purpose 

This range specification indicates that the 
editor command is to be applied to a line a 
fixed number of lines from a given line. 



Format 



Requirements 



Prompts & 
Responses 



Effects 



Examples 



range-1 + n 

1. Range-1 must be a range specification 
take from the list . (period), %BEGIN, 
and quoted or double quoted string. 

2. N must be an unsigned, no-zero number. 



None . 



None . 



1. The command is applied to the n-th line 
from the line indicated by range-1. 



lire /bDHuIN + 3 



S /FOO/BAR/ .+1 
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